5.5 Examining Variables

Do you find yourself repeatedly typing, e.g. print,n_elements(x), and similar statements to remind yourself of the type/size/structure/value/etc. of variables and expressions in your code or at the command line? IDLWAVE has a suite of special commands to automate these types of variable or expression examinations. They work by sending statements to the shell formatted to include the indicated expression, and can be accessed in several ways.

These examine commands can be used in the shell or buffer at any time (as long as the shell is running), and are very useful when execution is stopped in a buffer due to a triggered breakpoint or error, or while composing a long command in the IDLWAVE shell. In the latter case, the command is sent to the shell and its output is visible, but point remains unmoved in the command being composed — you can inspect the constituents of a command you're building without interrupting the process of building it! You can even print arbitrary expressions from older input or output further up in the shell window — any expression, variable, number, or function you see can be examined.

If the variable idlwave-shell-separate-examine-output is non-nil (the default), all examine output will be sent to a special *Examine* buffer, rather than the shell. The output of prior examine commands is saved in this buffer. In this buffer <c> clears the contents, and <q> hides the buffer.

The two most basic examine commands are bound to C-c C-d C-p, to print the expression at point, and C-c C-d ?, to invoke help on this expression¹. The expression at point is either an array expression or a function call, or the contents of a pair of parentheses. The chosen expression is highlighted, and simultaneously the resulting output is highlighted in the shell or separate output buffer. Calling the above commands with a prefix argument will use the current region as expression instead of using the one at point. which can be useful for examining complicated, multi-line expressions. Two prefix arguments (C-u C-u C-c C-d C-p) will prompt for an expression to print directly. By default, when invoking print, only an initial portion of long arrays will be printed, up to idlwave-shell-max-print-length.

For added speed and convenience, there are mouse bindings which allow you to click on expressions and examine their values. Use S-Mouse-2 to print an expression and C-M-Mouse-2 to invoke help (i.e. you need to hold down <META> and <CONTROL> while clicking with the middle mouse button). If you simply click, the nearest expression will be selected in the same manner as described above. You can also drag the mouse in order to highlight exactly the specific expression or sub-expression you want to examine. For custom expression examination, and the powerful customizable pop-up examine selection, See Custom Expression Examination.

The same variable inspection commands work both in the IDL Shell and IDLWAVE buffers, and even for variables at higher levels of the calling stack. For instance, if you're stopped at a breakpoint in a routine, you can examine the values of variables and expressions inside its calling routine, and so on, all the way up through the calling stack. Simply step up the stack, and print variables as you see them (see Walking the Calling Stack, for information on stepping back through the calling stack). The following restrictions apply for all levels except the current:

• Array expressions must use the ‘[ ]’ index delimiters. Identifiers with a ‘( )’ will be interpreted as function calls.
• N.B.: printing values of expressions on higher levels of the calling stack uses the unsupported IDL routine ROUTINE_NAMES, which may or may not be available in future versions of IDL. Caveat Examinor.